<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="set-example.html" />
<link rel="prev" href="module-sets.html" />
<link rel="parent" href="module-sets.html" />
<link rel="next" href="set-example.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>5.7.1 Set Objects </title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.7 sets  "
  href="module-sets.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="5.7 sets  "
  href="module-sets.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="5.7.2 Example"
  href="set-example.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-sets.html">5.7 sets  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-sets.html">5.7 sets  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="set-example.html">5.7.2 Example</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION007710000000000000000"></a><a name="set-objects"></a>
<br>
5.7.1 Set Objects 
</h2>

<p>
Instances of <tt class="class">Set</tt> and <tt class="class">ImmutableSet</tt> both provide
the following operations:

<p>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="center">Operation</th>
      <th class="center">Equivalent</th>
      <th class="left"  >Result</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="center" valign="baseline"><code>len(<var>s</var>)</code></td>
        <td class="center"></td>
        <td class="left"  >cardinality of set <var>s</var></td></tr><p>

    <tr><td class="center" valign="baseline"><code><var>x</var> in <var>s</var></code></td>
        <td class="center"></td>
        <td class="left"  >test <var>x</var> for membership in <var>s</var></td></tr>
    <tr><td class="center" valign="baseline"><code><var>x</var> not in <var>s</var></code></td>
        <td class="center"></td>
        <td class="left"  >test <var>x</var> for non-membership in <var>s</var></td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.issubset(<var>t</var>)</code></td>
        <td class="center"><code><var>s</var> &lt;= <var>t</var></code></td>
        <td class="left"  >test whether every element in <var>s</var> is in <var>t</var></td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.issuperset(<var>t</var>)</code></td>
        <td class="center"><code><var>s</var> &gt;= <var>t</var></code></td>
        <td class="left"  >test whether every element in <var>t</var> is in <var>s</var></td></tr><p>

    <tr><td class="center" valign="baseline"><code><var>s</var>.union(<var>t</var>)</code></td>
        <td class="center"><var>s</var> | <var>t</var></td>
        <td class="left"  >new set with elements from both <var>s</var> and <var>t</var></td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.intersection(<var>t</var>)</code></td>
        <td class="center"><var>s</var> &amp; <var>t</var></td>
        <td class="left"  >new set with elements common to <var>s</var> and <var>t</var></td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.difference(<var>t</var>)</code></td>
        <td class="center"><var>s</var> - <var>t</var></td>
        <td class="left"  >new set with elements in <var>s</var> but not in <var>t</var></td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.symmetric_difference(<var>t</var>)</code></td>
        <td class="center"><var>s</var> ^ <var>t</var></td>
        <td class="left"  >new set with elements in either <var>s</var> or <var>t</var> but not both</td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.copy()</code></td>
        <td class="center"></td>
        <td class="left"  >new set with a shallow copy of <var>s</var></td></tr></tbody>
</table></div>

<p>
Note, the non-operator versions of <tt class="method">union()</tt>,
<tt class="method">intersection()</tt>, <tt class="method">difference()</tt>, and
<tt class="method">symmetric_difference()</tt> will accept any iterable as an argument.
In contrast, their operator based counterparts require their arguments to
be sets.  This precludes error-prone constructions like
<code>Set('abc') &amp; 'cbs'</code> in favor of the more readable
<code>Set('abc').intersection('cbs')</code>.

<span class="versionnote">Changed in version 2.3.1:
Formerly all arguments were required to be sets.</span>

<p>
In addition, both <tt class="class">Set</tt> and <tt class="class">ImmutableSet</tt>
support set to set comparisons.  Two sets are equal if and only if
every element of each set is contained in the other (each is a subset
of the other).
A set is less than another set if and only if the first set is a proper
subset of the second set (is a subset, but is not equal).
A set is greater than another set if and only if the first set is a proper
superset of the second set (is a superset, but is not equal).

<p>
The subset and equality comparisons do not generalize to a complete
ordering function.  For example, any two disjoint sets are not equal and
are not subsets of each other, so <em>all</em> of the following return
<code>False</code>:  <code><var>a</var>&lt;<var>b</var></code>, <code><var>a</var>==<var>b</var></code>, or
<code><var>a</var>&gt;<var>b</var></code>.
Accordingly, sets do not implement the <tt class="method">__cmp__</tt> method.

<p>
Since sets only define partial ordering (subset relationships), the output
of the <tt class="method">list.sort()</tt> method is undefined for lists of sets.

<p>
The following table lists operations available in <tt class="class">ImmutableSet</tt>
but not found in <tt class="class">Set</tt>:

<p>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="center">Operation</th>
      <th class="left"  >Result</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="center" valign="baseline"><code>hash(<var>s</var>)</code></td>
        <td class="left"  >returns a hash value for <var>s</var></td></tr></tbody>
</table></div>

<p>
The following table lists operations available in <tt class="class">Set</tt>
but not found in <tt class="class">ImmutableSet</tt>:

<p>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="center">Operation</th>
      <th class="center">Equivalent</th>
      <th class="left"  >Result</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="center" valign="baseline"><code><var>s</var>.update(<var>t</var>)</code></td>
        <td class="center"><var>s</var> |= <var>t</var></td>
        <td class="left"  >return set <var>s</var> with elements added from <var>t</var></td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.intersection_update(<var>t</var>)</code></td>
        <td class="center"><var>s</var> &amp;= <var>t</var></td>
        <td class="left"  >return set <var>s</var> keeping only elements also found in <var>t</var></td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.difference_update(<var>t</var>)</code></td>
        <td class="center"><var>s</var> -= <var>t</var></td>
        <td class="left"  >return set <var>s</var> after removing elements found in <var>t</var></td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.symmetric_difference_update(<var>t</var>)</code></td>
        <td class="center"><var>s</var> ^= <var>t</var></td>
        <td class="left"  >return set <var>s</var> with elements from <var>s</var> or <var>t</var>
          but not both</td></tr><p>

    <tr><td class="center" valign="baseline"><code><var>s</var>.add(<var>x</var>)</code></td>
        <td class="center"></td>
        <td class="left"  >add element <var>x</var> to set <var>s</var></td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.remove(<var>x</var>)</code></td>
        <td class="center"></td>
        <td class="left"  >remove <var>x</var> from set <var>s</var>; raises <tt class="exception">KeyError</tt>
	  if not present</td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.discard(<var>x</var>)</code></td>
        <td class="center"></td>
        <td class="left"  >removes <var>x</var> from set <var>s</var> if present</td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.pop()</code></td>
        <td class="center"></td>
        <td class="left"  >remove and return an arbitrary element from <var>s</var>; raises
	  <tt class="exception">KeyError</tt> if empty</td></tr>
    <tr><td class="center" valign="baseline"><code><var>s</var>.clear()</code></td>
        <td class="center"></td>
        <td class="left"  >remove all elements from set <var>s</var></td></tr></tbody>
</table></div>

<p>
Note, the non-operator versions of <tt class="method">update()</tt>,
<tt class="method">intersection_update()</tt>, <tt class="method">difference_update()</tt>, and
<tt class="method">symmetric_difference_update()</tt> will accept any iterable as
an argument.

<span class="versionnote">Changed in version 2.3.1:
Formerly all arguments were required to be sets.</span>

<p>
Also note, the module also includes a <tt class="method">union_update()</tt> method
which is an alias for <tt class="method">update()</tt>.  The method is included for
backwards compatibility.  Programmers should prefer the
<tt class="method">update()</tt> method because it is supported by the builtin
<tt class="class">set()</tt> and <tt class="class">frozenset()</tt> types.

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="5.7 sets  "
  href="module-sets.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="5.7 sets  "
  href="module-sets.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="5.7.2 Example"
  href="set-example.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-sets.html">5.7 sets  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-sets.html">5.7 sets  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="set-example.html">5.7.2 Example</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
